home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Online / Miami / MiamiSDK / doc / MiamiBPF.doc < prev    next >
Text File  |  1997-12-23  |  13KB  |  384 lines
  1. TABLE OF CONTENTS
  2.  
  3. miamibpf.library/--general information--
  4. miamibpf.library/--packet format--
  5. miamibpf.library/MiamiBPFClose
  6. miamibpf.library/MiamiBPFFilter
  7. miamibpf.library/MiamiBPFInit
  8. miamibpf.library/MiamiBPFIoctl
  9. miamibpf.library/MiamiBPFOpen
  10. miamibpf.library/MiamiBPFRead
  11. miamibpf.library/MiamiBPFSetAbortmask
  12. miamibpf.library/MiamiBPFSignalmask
  13. miamibpf.library/--general information--
  14.  
  15.     Miami:libs/miamibpf.library is an implementation of the
  16.     Berkeley Packet Filter, an efficient, portable packet filtering
  17.     mechansim for BSD-derived protocol stack.
  18.  
  19.     MiamiBPF is implemented on top of the packet monitoring callback
  20.     mechanism in Miami 1.9.3 and above, and because of that only works
  21.     with the registered version of Miami.
  22.  
  23.     The main advantages of MiamiBPF over the standard packet monitoring
  24.     callback are:
  25.  
  26.     - MiamiBPF provides a socket-like API for monitoring that may be
  27.       easier to use in some situations than a callback hook.
  28.  
  29.     - MiamiBPF takes care of the necessary buffering, task switching and
  30.       signalling, so you can run all your packet analysis/debugging code
  31.       on your own task schedule.
  32.  
  33.     - MiamiBPF supports BPF programs, i.e.    virtual machine code allowing
  34.       you to very efficiently pre-filter packets.  BPF virtual machine
  35.       code is executed within the callback hook, so packets filtered out
  36.       by the virtual machine code do not create task switching overhead.
  37.  
  38.     - MiamiBPF adjusts itself to the speed of Miami and your program.  If
  39.       your program gets behind in analyzing packets then MiamiBPF
  40.       automatically drops packets so Miami does not get slowed down by
  41.       your program.
  42.  
  43.     A detailed description of the BPF virtual machine language is beyond
  44.     the scope of this document.  If you want to write your own BPF
  45.     programs then you should get the standard BPF documentation (for BSD)
  46.     from the Internet or from other sources.
  47.  
  48. miamibpf.library/--packet format--       miamibpf.library/--packet format--
  49.  
  50.     The BPF standard by itself does not define the format of packets
  51.     (e.g.  the size and type of link-layer headers) BPF programs operate
  52.     on.  This can be a problem for the BPF programmer because a BPF
  53.     program has to be adjusted to each interface individually.
  54.  
  55.     With MiamiBPF this is a bit different: MiamiBPF only operates on the
  56.     packet payload, not on the link-layer header, so all packets
  57.     processed by MiamiBPF have an identical format, regardless of which
  58.     interface they came from.
  59.  
  60.     Before MiamiBPF passes a packet to a BPF program it prepends the
  61.     following (virtual) header:
  62.  
  63.     - 1 byte: packet type (MIAMIPFBPT_...)
  64.  
  65.     - 1 byte: link type (always DLT_MIAMI)
  66.  
  67.     - 14 bytes: reserved: currently padded with zero.
  68.  
  69.     This means that your BPF program can identify the packet type (Arp,
  70.     IP etc.) by reading byte zero.    The actual packet contents are
  71.     located starting at offset 16.
  72.  
  73.     The virtual packet header is automatically added by MiamiBPF to any
  74.     packet arriving at MiamiBPF.  This includes packets arriving from
  75.     Miami and packets passed in through MiamiBPFFilter.
  76.  
  77.     Packets read by MiamiBPFRead include the virtual packet header.
  78.  
  79. miamibpf.library/MiamiBPFClose               miamibpf.library/MiamiBPFClose
  80.  
  81.    NAME
  82.     MiamiBPFClose -- Closes a BPF channel
  83.  
  84.    SYNOPSIS
  85.     MiamiBPFClose( channel );
  86.                D0
  87.  
  88.     void MiamiBPFClose( ULONG channel );
  89.  
  90.    FUNCTION
  91.     Closes the specified BPF channel, detaches it from its current
  92.     interface, and frees all related resources.
  93.  
  94.    INPUTS
  95.     channel - BPF channel
  96.  
  97. miamibpf.library/MiamiBPFFilter           miamibpf.library/MiamiBPFFilter
  98.  
  99.    NAME
  100.     MiamiBPFFilter -- Executes a BPF virtual machine program for a packet
  101.  
  102.    SYNOPSIS
  103.     retval = MiamiBPFFilter( program, packet, length, ptype );
  104.     D0             A0      A1      D0      D1
  105.  
  106.     unsigned long MiamiBPFFilter( struct bpf_insn *program, unsigned char
  107.         *packet, unsigned long length, char ptype );
  108.  
  109.    FUNCTION
  110.     Executes a BPF virtual machine program on a packet.  Both the BPF
  111.     program and the packet have to be specified in the function call.
  112.  
  113.     The program is specified by a pointer to an array of (compiled) BPF
  114.     instructions.
  115.  
  116.     The packet is specified by a pointer to the first byte in the packet
  117.     and by the packet length.
  118.  
  119.     The value returned by MiamiBPFFilter is the value returned by a RET
  120.     instruction in your program.  The return value is undefined if your
  121.     program is malformed.
  122.  
  123.    INPUTS
  124.     program - First instruction of BPF program
  125.  
  126.     packet - Packet to filter
  127.  
  128.     length - Packet length
  129.  
  130.     ptype - Packet type (MIAMIPFBPT_...)
  131.  
  132.    RESULT
  133.     retval (D0) - Return value
  134.  
  135.    NOTE
  136.     The packet MAY NOT contain any link-layer header.  The first byte of
  137.     the packet has to be the first byte visible to the protocol stack.
  138.  
  139.     This function is NOT needed if you just want to listen for packets on
  140.     one of Miami's interfaces.  It can be useful though if you want a BPF
  141.     filter to execute on packets arriving from some OTHER source, e.g.
  142.     when reading packets from a file.
  143.  
  144. miamibpf.library/MiamiBPFInit            miamibpf.library/MiamiBPFInit
  145.  
  146.    NAME
  147.     MiamiBPFInit -- initialize MiamiBPF
  148.  
  149.    SYNOPSIS
  150.     MiamiBPFInit( MiamiBase, SocketBase );
  151.               A0     A0
  152.  
  153.     void MiamiBPFInit( struct Library *MiamiBase, struct Library
  154.         *SocketBase );
  155.  
  156.    FUNCTION
  157.     Initializes MiamiBPF for use.  You MUST call this function before
  158.     calling any other function in miamibpf.library.
  159.  
  160.    INPUTS
  161.     MiamiBase - Library base of miami.library
  162.  
  163.     SocketBase - Library base of bsdsocket.library
  164.  
  165.    NOTE
  166.     You need to open miami.library V6 or higher and bsdsocket.library V4
  167.     or higher before calling this function.  Mind the version numbers !
  168.     Using miamimpf.library with older library versions will cause
  169.     crashes.
  170.  
  171. miamibpf.library/MiamiBPFIoctl               miamibpf.library/MiamiBPFIoctl
  172.  
  173.    NAME
  174.     MiamiBPFIoctl -- Reads or writes control information for a BPF
  175.     channel
  176.  
  177.    SYNOPSIS
  178.     error = MiamiBPFIoctl( channel, command, data );
  179.     D0               D0    D1     A0
  180.  
  181.     LONG MiamiBPFIoctl( ULONG channel, ULONG command, UBYTE *data );
  182.  
  183.    FUNCTION
  184.     Reads or writes control or state information associated with a
  185.     previously opened BPF channel.    The following commands are valid:
  186.  
  187.     - FIONREAD: 'data' needs to point to a longword (at least
  188.       word-aligned).  When the call returns that longword contains the
  189.       number of bytes ready for reading from this BPF channel.
  190.  
  191.     - SIOCGIFADDR: 'data' needs to point to a 'struct ifreq', with
  192.       ifr_name initialized to a valid interface name.  When the call
  193.       returns the 'struct ifreq' has been filled with address information
  194.       for AF_INET for the specified interface.
  195.  
  196.     - BIOCGBLEN: 'data' needs to point to a longword (at least
  197.       word-aligned).  When the call returns that longword contains the
  198.       current size of a BPF packet buffer.
  199.  
  200.     - BIOCSBLEN: 'data' needs to point to a longword (at least
  201.       word-aligned), that contains the desired size of the BPF packet
  202.       buffer.
  203.  
  204.     - BIOCSETF: 'data' needs to point to a 'struct bpf_program' that
  205.       contains a valid, compiled BPF virtual machine code program.    When
  206.       the call returns MiamiBPF has attached that program to the BPF
  207.       channel, so all subsequent packets will be filtered using the new
  208.       program.
  209.  
  210.     - BIOCFLUSH: all current read buffers are emptied.
  211.  
  212.     - BIOCGETIF: 'data' needs to point to a 'struct ifreq'.  When the
  213.       call returns ifr_name has been initialized with the name of the
  214.       interface the BPF channel is currently attached to.
  215.  
  216.     - BIOCSETIF: 'data' needs to point to a 'struct ifreq', with ifr_name
  217.       initialized to a valid interface name.  When the call returns the
  218.       BPF channel has been attached to the specified interface, i.e.
  219.       packets arriving at that interface or sent through that interface
  220.       are directed to the BPF channel.
  221.  
  222.     - BIOCSRTIMEOUT: 'data' needs to point to a 'struct timeval' that
  223.       contains the new timeout for a call to MiamiBPFRead.
  224.  
  225.     - BIOCGRTIMEOUT: 'data' needs to point to a 'struct timeval'.  When
  226.       the call returns that 'struct timeval' contains the current timeout
  227.       for a call to MiamiBPFRead.
  228.  
  229.     - BIOCGSTATS: 'data' needs to point to a 'struct bpf_stat'.  When the
  230.       call returns that 'struct bpf_stat' contains the current packet
  231.       statistics for this BPF channel.
  232.  
  233.     - BIOCIMMEDIATE: 'data' needs to point to a 'unsigned int' defining
  234.       the state of the 'immediate' flag (TRUE/FALSE).  Usually MiamiBPF
  235.       only completes a MiamiBPFRead call when a read buffer is full or
  236.       when the read timeout is expired.  However if the 'immediate' flag
  237.       is set to TRUE then MiamiBPFRead completes after EACH packet
  238.       received.
  239.  
  240.     - BIOCVERSION: 'data' needs to point to a 'struct bpf_version'.  When
  241.       the call returns that 'struct bpf_version' contains the major and
  242.       minor version numbers for this implementation of the BPF code
  243.       engine.
  244.  
  245.     The returned 'error' value is negative if an error has occured, and
  246.     zero if the function completed successfully.
  247.  
  248.    INPUTS
  249.     channel - BPF channel
  250.  
  251.     command - command (usually BIOC...)
  252.  
  253.     data - data for the command
  254.  
  255.    RESULT
  256.     error (D0) - error condition
  257.  
  258. miamibpf.library/MiamiBPFOpen            miamibpf.library/MiamiBPFOpen
  259.  
  260.    NAME
  261.     MiamiBPFOpen -- Opens a new BPF channel
  262.  
  263.    SYNOPSIS
  264.     channel = MiamiBPFOpen( tags );
  265.     D0            A0
  266.  
  267.     ULONG MiamiBPFOpen( struct TagList *tags );
  268.  
  269.    FUNCTION
  270.     Opens a new BPF channel.  The channel is set to default settings, and
  271.     not attached to any interface.
  272.  
  273.     The returned value is either 0 if the function has failed, or a valid
  274.     BPF channel (a value different from 0).
  275.  
  276.     The taglist should be NULL for compatibility to future versions.
  277.  
  278.     All open BPF channels are automatically closed when miamibpf.library
  279.     is closed.
  280.  
  281.     Note that BPF channels are quite different from socket numbers.  You
  282.     CANNOT use BPF channel numbers in an FD_SET (e.g.  in a WaitSelect
  283.     call).
  284.  
  285.    INPUTS
  286.     tags - taglist (not used)
  287.  
  288.    RESULT
  289.     channel (D0) - BPF channel
  290.  
  291. miamibpf.library/MiamiBPFRead            miamibpf.library/MiamiBPFRead
  292.  
  293.    NAME
  294.     MiamiBPFRead -- Reads packets from a BPF channel
  295.  
  296.    SYNOPSIS
  297.     length = MiamiBPFRead( channel, buffer, maxlen );
  298.     D0               D0    A0    D1
  299.  
  300.     LONG MiamiBPFRead( ULONG channel, UBYTE *buffer, ULONG maxlen );
  301.  
  302.    FUNCTION
  303.     Reads one or more packets from a BPF channel.  This function blocks
  304.     until data is available for reading.  Whether the function returns
  305.     for EACH packet or only after several packets have been read depends
  306.     on the state of the 'immediate' flag for this BPF channel (see
  307.     MiamiBPFIoctl).
  308.  
  309.     'maxlen' has to be EXACTLY IDENTICAL to the current buffer size for
  310.     this channel, or MiamiBPFRead immediately returns -1.  You can
  311.     set/get the current buffer size through MiamiBPFIoctl.
  312.  
  313.     A 'length' value greater than zero indicates the number of bytes read
  314.     (one or more packets).    A value of zero indicates that a timeout has
  315.     occured.  A value less than zero indicates that an error has occured
  316.     or that one or more signals in the current abort mask have arrived.
  317.     In the latter case use SetSignal to find out which signal has
  318.     arrived.
  319.  
  320.    INPUTS
  321.     channel - BPF channel
  322.  
  323.     buffer - packet buffer
  324.  
  325.     maxlen - size of the packet buffer
  326.  
  327.    RESULT
  328.     length (D0) - number of bytes returned
  329.  
  330. miamibpf.library/MiamiBPFSetAbortmask    miamibpf.library/MiamiBPFSetAbortmask
  331.  
  332.    NAME
  333.     MiamiBPFSetAbortmask -- Defines the abort mask for a BPF channel
  334.  
  335.    SYNOPSIS
  336.     MiamiBPFSetAbortmask( channel, signals );
  337.                   D0       D0
  338.  
  339.     void MiamiBPFSetAbortmask( ULONG channel, ULONG signals );
  340.  
  341.    FUNCTION
  342.     Usually a MiamiBPFRead command only returns when data is available
  343.     for reading or when the read timeout (if any) has expired.
  344.  
  345.     This function allows you define an additional condition when you want
  346.     MiamiBPFRead to return, e.g.  when the user hits Ctrl-C.
  347.  
  348.    INPUTS
  349.     channel - BPF channel
  350.  
  351.     signals - abort mask
  352.  
  353.    EXAMPLE
  354.     MiamiBPFSetAbortmask(channel,SIGBREAKF_CTRL_C);
  355.  
  356. miamibpf.library/MiamiBPFSignalmask      miamibpf.library/MiamiBPFSignalmask
  357.  
  358.    NAME
  359.     MiamiBPFSignalmask -- Returns the signal mask for a BPF channel
  360.  
  361.    SYNOPSIS
  362.     signals = MiamiBPFSignalmask( channel );
  363.     D0                  D0
  364.  
  365.     ULONG MiamiBPFSignalmask( ULONG channel );
  366.  
  367.    FUNCTION
  368.     Each open BPF channel has an associated signal mask that is set
  369.     whenever a MiamiBPFRead function would complete.  That signal mask is
  370.     returned by this function.
  371.  
  372.     If you want to ensure that MiamiBPFRead does not block then you need
  373.     to first check if data is available for reading (FIONREAD).  If not
  374.     then wait for the signal(s) returned by MiamiBPFSignalmask to be set
  375.     for your task, and check again (FIONREAD).  Call MiamiBPFRead only if
  376.     FIONREAD returns a non-zero number of bytes.
  377.  
  378.    INPUTS
  379.     channel - BPF channel
  380.  
  381.    RESULT
  382.     signals (D0) - signal mask
  383.  
  384.